@rpldy/uploader
Advanced tools
The Uploader is the processing and queuing engine for React-Uploady. When files are handed to the Uploader, it will represent each file as a Batch Item and group them together in Batches. This is for the most part internal to the uploading mechanism.
The Uploader fires Batch & BatchItem lifecycle events that can be registered to. Some of these events also allow to cancel uploads dynamically.
_If you're looking to integrate file upload with your React app, you'd probably want to head over to the @rpldy/uploady README.
#Yarn:
$ yarn add @rpldy/uploader
#NPM:
$ npm i @rpldy/uploader
When in React, you don't need to use this package directly. Uploady will take care of initialization and other aspects (ie: event registration) for you. In case you want to create your own uploader instance, you can do it like so:
import createUploader, { UPLOADER_EVENTS } from "@rpldy/uploader";
const uploader = createUploader({
autoUpload: false,
grouped: true,
//...
});
uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
console.log(`item ${item.id} started uploading`);
});
uploader.add(myFile);
| Name (* = mandatory) | Type | Default | Description |
|---|---|---|---|
| autoUpload | boolean | true | automatically upload files when they are added |
| destination | Destination | undefined | configure the end-point to upload to |
| inputFieldName | string | "file" | name (attribute) of the file input field (requires sendWithFormData = true) |
| grouped | boolean | false | group multiple files in a single request |
| maxGroupSize | number | 5 | maximum of files to group together in a single request |
| formatGroupParamName | (number, string) => string | undefined | determine the upload request field name when more than file is grouped in a single upload |
| fileFilter | (File | string, index: number, File[] | string[]) => boolean | undefined | return false to exclude from batch |
| method | string | "POST" | HTTP method in upload request |
| params | Object | undefined | collection of params to pass along with the upload (requires sendWithFormData = true) |
| forceJsonResponse | boolean | false | parse server response as JSON even if no JSON content-type header received |
| withCredentials | boolean | false | set XHR withCredentials to true |
| enhancer | UploaderEnhancer | undefined | uploader enhancer function |
| concurrent | boolean | false | issue multiple upload requests simultaneously |
| maxConcurrent | number | 2 | maximum allowed simultaneous requests |
| send | SendMethod | @rpldy/sender | how to send files to the server |
| sendWithFormData | boolean | true | upload is sent as part of formdata - when true, additional params can be sent along with uploaded data |
(files: UploadInfo | UploadInfo[], options?: ?UploadOptions) => void
The way to add file(s) to be uploaded. Second parameters allows to pass different options than the ones the instance currently uses for this specific batch. These options will be merged with current instance options.
() => void
For batches that were added with autoUpload = false, the upload method must be called for the files to begin uploading.
(id?: string) => void
abort all files being uploaded or a single item by its ID
(id: string) => void
abort a specific batch by its ID
(options: UploadOptions) => UploaderType
options parameter will be merged with the instance's existing options Returns the uploader instance
() => CreateOptions
get the instance's upload options
() => PendingBatch[]
get pending batches that were added with autoUpload = false.
() => void
remove all batches that were added with autoUpload = false and were not sent to upload yet.
register an event handler
register an event handler that will be called only once
unregister an existing event handler
(name: any, Object) => void
Extensions can only be registered by enhancers. If registerExtension is called outside an enhancer, an error will be thrown Name must be unique. If not, an error will be thrown
(name: any) => ?Object_
Retrieve a registered extension by its name
The Uploader will trigger for batch and batch-item lifecycle events.
Registering to handle events can be done using the uploader's on() and once() methods. Unregistering can be done using off() or by the return value of both on() and once().
const batchAddHandler = (batch) => {};
const unregister = uploader.on(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);
unregister(); //is equivalent to the line below
uploader.off(UPLOADER_EVENTS.BATCH_ADD, batchAddHandler);
Triggered when a new batch is added.
This event is cancellable
Triggered when batch items start uploading
This event is cancellable
Triggered every time progress data is received from the upload request(s)
Triggered when batch items finished uploading
Triggered in case batch was cancelled from BATCH_START event handler
Triggered in case the batch was aborted
Triggered when item starts uploading (just before) For grouped uploads (multiple files in same xhr request) ITEM_START is triggered for each item separately
This event is cancellable
Triggered when item finished uploading successfully
The server response can be accessed through the item's uploadResponse property.
Triggered every time progress data is received for this file upload
progress info is accessed through the item's "completed" (percentage) and "loaded" (bytes) properties.
Triggered in case item was cancelled from ITEM_START event handler
Triggered in case item upload failed
The server response can be accessed through the item's uploadResponse property.
Triggered in case abort was called
Triggered for item when uploading is done due to: finished, error, cancel or abort Use this event if you want to handle the state of the item being done for any reason.
Triggered before a group of items is going to be uploaded Group will contain a single item unless "grouped" option is set to true.
Handler receives the item(s) in the group and the upload options that were used. The handler can change data inside the items and in the options by returning different data than received. See this guide for more details.
This event is cancellable
Triggered when abort is called without an item id (abort all)
These are events that allow the client to cancel their respective upload object (batch or batch-item) To cancel the upload, the handler must return (boolean) false.
uploader.on(UPLOADER_EVENTS.ITEM_START, (item) => {
let result;
if (item.file.name.endsWith(".xml")) {
result = false; //only false will cause a cancel.
}
return result;
});
0.8.3 (2021-01-07)
[uploader] - respect filesParamName in upload options. Fix for #117[retry] - use item finalize event instead of error & aborte2e - added uploady custom filesParamName specFAQs
the processing and queuing engine for react-uploady
The npm package @rpldy/uploader receives a total of 11,917 weekly downloads. As such, @rpldy/uploader popularity was classified as popular.
We found that @rpldy/uploader demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.